home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1989 …il & Dave's Excellent CD / Excellent CD HFS.raw / Moof / Goodies / DTS Goodies / Hardware Hints / Slot Tools / Notes on the tools < prev    next >
Encoding:
Text File  |  1988-11-28  |  9.3 KB  |  198 lines  |  [TEXT/MPS ]
  1. Here are some notes on the applications and tools in this folder, as well as some
  2. additional notes about the slot manager in general:
  3.  
  4.  
  5. 1.  CRCPATCH
  6.  
  7. The crcpatch tool calculates the crc value.  See the example build sequence below for 
  8. the invocation sequence.  It is run after the declaration ROM file has been assembled 
  9. and linked.
  10.  
  11. The crcpatch tool calculates the crc value using this algorithm:
  12.  
  13. Start pointer at bottom of ROM (top of ROM - length)
  14. Initialize sum to 0 (sum will be the CRC value)
  15. @1     Rotate sum left by one bit (with ROL.L #1 instruction)
  16.           If pointer is pointing to CRC field in format header, goto @2 (i.e. don't count CRC field)
  17.        Get a byte
  18.        Add byte to sum
  19. @2     Increment pointer to next data byte
  20. Goto @1 until done
  21.  
  22.  
  23. 2.  DATA TOOL
  24.  
  25. The data tool strips off the code 0 segment, and puts the code 1 segment in a data 
  26. file, so the data file can be downloaded to a rom burner.
  27.  
  28.  
  29. 3.  TJSCOMM APPLICATION
  30.  
  31. The tjscomm application is a rudimentary data comm program.  It can be used to download 
  32. data file to a ROM burner.
  33.  
  34.  
  35. 4.  GETSINFO APPLICATION
  36.  
  37. The GetsInfo application prints out some summary info for cards in certain slots.  Don't 
  38. worry about the slot 0 error, as future Macintosh II ROMs will contain a slot 0
  39. sResource.
  40.  
  41.  
  42. 5.  SLOTMGRTEST APPLICATION
  43.  
  44. The SlotMgrTst application exercises the slot manager.  It runs continuously, and the only way 
  45. to stop it is to bring down and hold down a menu.  It has limited usefullness but is included 
  46. anyway.
  47.  
  48.  
  49. 6.  BUILDING A CONFIG ROM USING THE TOOLS
  50.  
  51. Here is an example of how the Apple Video ROM Code was built:
  52.  
  53.  
  54. ## Assemble and link the ROM
  55. directory "{Decl}TFB-b1:"
  56. asm -wb -i {AIncludes}nFiles  -i {Decl} VideoROM.a
  57. Link VideoROM.a.o   -o videoROM
  58.  
  59. ### Patch the crc value and then convert the code to a data file.
  60. ### in this case, operate on the linked declaration file (videoROM)
  61. Tools:crcPatch" videoROM
  62. Tools:Data" videoROM  tfbROM1.d
  63.  
  64.  
  65. 7.  MBGETSINFO APPLICATION
  66.  
  67. The GetSInfo application used a preliminary (Beta) slot manager interface that changed radically 
  68. when the Macintosh II went into final production.  mbgetsinfo is a very preliminary sampe that uses
  69. the real slot manager interface.  It checks the slots, and displays a partial summary of what is in 
  70. the slots.  It doesn't go as far as getting to the vendor info, that is something I'll fix up later.  
  71. It will show you how to use the slot manager, though.  Once you see how this program gets to data
  72. structures, you can extend it to the rest of the slot manager.
  73.  
  74. The user interface is hideous, of course.  It uses writelns, doesn't update, etc.  I'd shoot myself 
  75. if I tried to ship this, but right now, it is an in house experiment only.  I'll make it a real
  76. Macintosh application yet!
  77.  
  78.  
  79.  
  80. 8.  GENERAL SLOT MANAGER DECLARATION ROM DISCUSSION
  81.  
  82. {semi-standard slot manager canned answer follows and may be disregarded if you are familier 
  83. with the slot manager}
  84.  
  85.  
  86.  
  87. Functional sResources are recommended in addition to the board sResource, and exist to 
  88. tell the world what type of function(s) your board can perform.  There is usually one 
  89. of these functional sResources for each function the board can perform.  Conceptually, each 
  90. sResource tells the world one function the card can perform.  The board sResource is sort 
  91. of a degenerate case of sResources: it exists to tell the slot manager that it can 
  92. perform the function of being a board (and it provides a handy place to store board 
  93. related data).  The board sResource which has a functional sRsrc_Type of:
  94.  
  95. CatBoard         EQU  $0001  ;always 1 for board sResource
  96. TypBoard         EQU  $0000  ;always 0 for board sResource
  97. DrSwBoard        EQU  $0000  ;always 0 for board sResource
  98. DrHwBoard        EQU  $0000  ;always 0 for board sResource
  99.  
  100.  
  101. A board resource is required if the slot manager is to be used at all, since if there 
  102. is no board resource, the slot manager will mark the slot as empty, and no slot manager
  103. calls to that slot will work.  
  104.  
  105. With this scheme, therefore, a multifunction card would have the board sResource, plus a 
  106. functional sResource for each function the board could perform.  as an example, if you had a 
  107. multifunction board that was a display card, a modem, a parallel i/o, and a SCSI card, you'd 
  108. have five sResources:
  109.  
  110.   the board sResource (as stated above boards should always have this)
  111.  
  112.   an sResource with an sRsrc_Type that has something like CatDisplay,
  113.   TypVideo, etc.
  114.  
  115.   an sResource with an sRsrc_Type that has something like CatCommunication,
  116.   TypModem, etc.
  117.  
  118.   an sResource with an sRsrc_Type that has something like CatCommunication,
  119.   TypParallel, etc.
  120.  
  121.   an sResource with an sRsrc_Type that has something like CatIntBus,
  122.   TypSCSI, etc.
  123.   
  124. MacDTS issues functional sResources equates for now; eventually you'll find standard Category, Type
  125. and SW ids in the MPW equates.  You will always need to have DTS assign you a unique DrHw equate
  126. since that is what differentiates unique hardware (i.e. boards), and you may need to have DTS assign
  127. a drSw equate if you have a unique driver interface that isn't in the equates (the most common 
  128. example of this is developers who make video boards compatible with the Apple video driver 
  129. interface - The CatDisplay, TypVideo, Category and Type have already been defined, as well as the
  130. Apple video driver interface, which is represented by the DrSwApple equate.  All a developer would
  131. need then would be a unique DrHw equate.   
  132.  
  133. Your application will then look for your board by basically calling SNextTypesRsrc after 
  134. filling in the spCategory, spCType, spDrvrSW, spDrvrHW fields calling for your functional 
  135. sRsrc_Type fields (see below for an example of how QuickDraw might look for an example).
  136.  
  137. There is an spTBMask field in the same SNextTypesRsrc call that allows you to mask off 
  138. any of these values (making them a don't care).  This is useful if you have a driver that 
  139. will take care of the underlying hardware, so you don't have to worry about particular hardware 
  140. revisions.  Most cards that have drivers on board will allow the app to mask off the spDrvrHW 
  141. field so the application will work with different revisions of the board.  Of course this 
  142. means less maintainence for the application programmer, and a much higher customer 
  143. satisfaction level, since their application won't cease to work if they buy a later 
  144. version of your board.  It allows you to rev your driver by sending the customer a new 
  145. ROM or init file without having the customer get a new version of the application.
  146.  
  147. Additionally, if you define a driver interface for your board (like Apple did with the 
  148. video driver), then other manufacturers can make applications that will find your board 
  149. by calling SNextTypesRsrc with the hw id again masked off, because they know your driver 
  150. will handle the underlying hardware, no matter what it is.   This should sell more of your 
  151. boards by providing more applications for the board.  Conversely, if you define a software 
  152. interface, other manufacturers can make compatible boards that your application will run 
  153. on.  This is exactly what Apple did by defining the video driver interface for QuickDraw.  All 
  154. QuickDraw does is call SNextTypesRsrc with the following sRsrc_Type fields, i.e.
  155.  
  156.   spCategory := catDisplay;
  157.   spCType := typVideo;
  158.   spDrvrSW := drSwApple;
  159.  
  160. again, masking off the spDrvrHW field.
  161.  
  162. Thus when QuickDraw makes the call it finds out all the compatible video boards which may 
  163. have been made by Apple, SuperMac, E-machines, etc.  All these boards have different hardware 
  164. but the individual drivers take care of everything.  This allows the customer to choose among 
  165. various boards for his/her system.
  166.  
  167. In summary, you want a configuation ROM with a board sResource and the functional sResource 
  168. listed above.  Ideally, you want a driver in ROM as well, but you could have your app carry 
  169. the driver or interface software inside the app.  This locks a particular app to a particular 
  170. rev of a board, and provides you the manufacturer with headaches shoudl you decide to rev or 
  171. change your board such that the app no longer works.  Then you might have to maintain different 
  172. versions of your app since your customers might have either version of your board.   Anything 
  173. that inconveniences the customer will almost certainly (and I am really serious here) subject 
  174. you to abuse and severe criticism from anyone who reviews your product.
  175.  
  176.  
  177. 9. HOW TO GET BOARD IDS AND SRESOURCE IDS
  178.  
  179. When a developer wishes to get board ids and/or functional sRsrc_Type values (Category, 
  180. cType, DrvrSw and DrvrHw values), then the developer needs to contact us here at MacDTS 
  181. with the following info:
  182.  
  183. - What the board will do (so we can assign the values)
  184. - the official product name for the board (or a code name)
  185. - whether or not the board will have a software driver other than one
  186.   which has been pre-defined (like Apple's video driver).
  187. - whether or not the board will have driver that will be on board 
  188.   (that is, in the ROM), or whether or not it will be a driver that
  189.   gets installed at init time, in the application, etc.
  190. - the company address (mailing and electronic mail addresses if possible) and the
  191.   name of the person in the company responsible for the board.
  192.  
  193. We then assign the values for Category, cType, DrvrSw and DrvrHw ids.
  194.  
  195. We need the above information because we are maintaining a database to prevent id 
  196. conflicts.  We don't give the database out because it will have unannounced products 
  197. on it.  You can be assured we keep all information confidential.
  198.